---
title: Markdown & MDX
description: Astro에서 Markdown 또는 MDX를 사용하여 콘텐츠를 만드는 방법을 알아보세요.
i18nReady: true
---

import Since from '~/components/Since.astro'
import { FileTree } from '@astrojs/starlight/components';
import RecipeLinks from '~/components/RecipeLinks.astro'
import ReadMore from '~/components/ReadMore.astro'

[Markdown](https://daringfireball.net/projects/markdown/)은 일반적으로 블로그 게시물 및 문서와 같이 텍스트가 많은 콘텐츠를 작성하는 데 사용됩니다. Astro에는 title, description, tags와 같은 사용자 정의 메타데이터를 정의하기 위해 [프런트매터 YAML](https://dev.to/paulasantamaria/introduction-to-yaml-125f)도 포함할 수 있는 표준 Markdown 파일에 대한 기본 지원이 포함되어 있습니다.

[@astrojs/mdx 통합](/ko/guides/integrations-guide/mdx/)이 설치되면 Astro는 Markdown 콘텐츠의 JavaScript 표현식 및 컴포넌트 지원과 같은 추가 기능을 제공하는 [MDX](https://mdxjs.com/) (`.mdx`) 파일도 지원합니다.

Markdown 콘텐츠를 작성하려면 두 가지 유형의 파일 중 하나 또는 두 가지를 모두 사용하세요!

## Markdown 및 MDX 페이지

### 콘텐츠 컬렉션

Astro의 특별한 `src/content/` 폴더에서 Markdown 및 MDX 파일을 관리할 수 있습니다. [콘텐츠 컬렉션](/ko/guides/content-collections/)은 콘텐츠를 구성하고, 프런트매터의 유효성을 검사하고, 콘텐츠 작업 중 자동 TypeScript 타입 안전성을 제공하는 데 도움이 됩니다.

<FileTree>
- src/content/
  - **newsletter/** 
    - week-1.md
    - week-2.md
  - **authors/**
    - grace-hopper.md
    - alan-turing.md
</FileTree>

[Astro의 콘텐츠 컬렉션](/ko/guides/content-collections/) 사용에 대해 자세히 알아보세요.

### 파일 기반 라우팅

Astro는 `/src/pages/` 디렉터리의 `.md` (또는 대체 지원 확장자) 또는 `.mdx` 파일을 페이지로 처리합니다.

이 디렉터리나 하위 디렉터리에 파일을 배치하면 파일의 경로 이름을 사용하여 페이지 경로가 자동으로 빌드됩니다.

```markdown
---
# Example: src/pages/page-1.md
title: Hello, World
---

# Hi there!

This Markdown file creates a page at `your-domain.com/page-1/`

It probably isn't styled much, but Markdown does support:
- **bold** and _italics._
- lists
- [links](https://astro.build)
- and more!
```

<ReadMore>Astro의 [파일 기반 라우팅](/ko/guides/routing/) 또는 [동적 경로](/ko/guides/routing/#동적-경로) 생성 옵션에 대해 자세히 알아보세요.</ReadMore>

## Markdown 기능

Astro는 Markdown 및 MDX 파일을 사용할 때 사용할 수 있는 몇 가지 추가 내장 Markdown 기능을 제공합니다.

### 프런트매터 `layout`

Astro는 Astro [레이아웃 컴포넌트](/ko/basics/layouts/#markdownmdx-레이아웃)에 대한 상대 경로 (또는 [별칭](/ko/guides/aliases/))를 지정할 수 있는 특별한 프런트매터 `layout` 속성이 있는 Markdown 및 MDX 페이지를 제공합니다.

```markdown {3}
---
# src/pages/posts/post-1.md
layout: ../../layouts/BlogPostLayout.astro
title: Astro in brief
author: Himanshu
description: Find out what makes Astro awesome!
--- 
This is a post written in Markdown.
```

그런 다음 `Astro.props`를 통해 [레이아웃 컴포넌트에 특정 속성을 사용할 수 있습니다](/ko/basics/layouts/#markdown-레이아웃-props). 예를 들어 `Astro.props.frontmatter`를 통해 frontmatter 속성에 액세스할 수 있습니다.

```astro /frontmatter(?:.\w+)?/
---
// src/layouts/BlogPostLayout.astro
const {frontmatter} = Astro.props;
---
<html>
  <!-- ... -->
  <h1>{frontmatter.title}</h1>
  <h2>Post author: {frontmatter.author}</h2>
  <p>{frontmatter.description}</p>
  <slot /> <!-- Markdown 콘텐츠가 여기에 삽입됩니다. -->
   <!-- ... -->
</html>
```

레이아웃 컴포넌트에서 [Markdown 스타일을 지정](/ko/guides/styling/#markdown-스타일링)할 수도 있습니다.

<ReadMore>[Markdown 레이아웃](/ko/basics/layouts/#markdownmdx-레이아웃)에 대해 자세히 알아보세요.</ReadMore>

### 제목 ID

Markdown 및 MDX의 제목을 사용하면 자동으로 앵커 링크가 제공되므로 페이지의 특정 섹션에 직접 연결할 수 있습니다.

```markdown title="src/pages/page-1.md"
---
title: My page of content
---
## Introduction

I can link internally to [my conclusion](#conclusion) on the same page when writing Markdown.

## Conclusion

I can use the URL `https://example.com/page-1/#introduction` to navigate directly to my Introduction on the page. 
```

Astro는 `github-slugger`를 기반으로 `id`라는 제목을 생성합니다. [github-slugger 문서](https://github.com/Flet/github-slugger#usage)에서 더 많은 예시를 찾을 수 있습니다.

### 특수 문자 이스케이프

특정 문자는 Markdown 및 MDX에서 특별한 의미를 갖습니다. 표시하려면 다른 구문을 사용해야 할 수도 있습니다. 이렇게 하려면 해당 문자에 대해 [HTML 엔터티](https://developer.mozilla.org/en-US/docs/Glossary/Entity)를 대신 사용할 수 있습니다.

예를 들어 `<`가 HTML 요소의 시작 부분으로 해석되는 것을 방지하려면 `&lt;`를 작성하세요. 또는 `{`가 MDX에서 JavaScript 표현식의 시작 부분으로 해석되는 것을 방지하려면 `&lcub;`를 작성하세요.

## MDX 전용 기능

Astro [MDX 통합](/ko/guides/integrations-guide/mdx/)을 추가하면 JSX 변수, 표현식, 컴포넌트를 사용하여 Markdown 작성이 향상됩니다.

또한 [MDX의 Markdown 스타일 프런트매터](https://mdxjs.com/guides/frontmatter/)에 대한 지원을 포함하여 표준 MDX에 추가 기능을 추가합니다. 이를 통해 [프런트매터 `layout`](#프런트매터-layout) 속성과 같은 Astro의 내장 Markdown 기능 대부분을 사용할 수 있습니다.

`.mdx` 파일은 Astro의 HTML과 같은 구문이 아닌 [MDX 구문](https://mdxjs.com/docs/what-is-mdx/#mdx-syntax)으로 작성되어야 합니다.

### MDX에서 내보낸 변수 사용

MDX는 `export` 구문을 사용하여 MDX 콘텐츠에 변수를 추가할 수 있도록 지원합니다. 이러한 변수는 템플릿 자체에서 액세스할 수 있을 뿐만 아니라 [파일을 다른 곳으로 가져올 때](#markdown-가져오기) 명명된 속성으로 액세스할 수 있습니다.

예를 들어 MDX 페이지 또는 컴포넌트에서 `title` 필드를 내보내 `{JSX 표현식}`의 제목으로 사용할 수 있습니다.

```mdx title="/src/pages/posts/post-1.mdx"
export const title = 'My first MDX post'

# {title}
```

### MDX에서 프런트매터 변수 사용

Astro MDX 통합에는 기본적으로 MDX에서 프런트매터 사용에 대한 지원이 포함되어 있습니다. Markdown 파일에서와 마찬가지로 프런트매터 속성을 추가하면 이러한 변수에 액세스하여 템플릿, [`layout` 컴포넌트](#프런트매터-layout), [파일을 다른 곳으로 가져올 때](#markdown-가져오기) 명명된 속성으로 사용할 수 있습니다.

```mdx title="/src/pages/posts/post-1.mdx"
---
layout: '../../layouts/BlogPostLayout.astro'
title: 'My first MDX post'
---

# {frontmatter.title}
```

### MDX에서 컴포넌트 사용

MDX 통합을 설치한 후 다른 Astro 컴포넌트에서 사용하는 것처럼 [Astro 컴포넌트](/ko/basics/astro-components/#컴포넌트-props)와 [UI 프레임워크 컴포넌트](/ko/guides/framework-components/#프레임워크-컴포넌트-사용하기)를 MDX (`.mdx`) 파일로 가져와 사용할 수 있습니다.

필요한 경우 UI 프레임워크 컴포넌트에 `client:directive`를 포함하는 것을 잊지 마세요!

[MDX 문서](https://mdxjs.com/docs/what-is-mdx/#esm)에서 가져오기 및 내보내기 구문 사용에 대한 추가 예시를 참조하세요.

```mdx title="src/pages/about.mdx" {5-6} /<.+\/>/
---
layout: ../layouts/BaseLayout.astro
title: About me
---
import Button from '../components/Button.astro';
import ReactCounter from '../components/ReactCounter.jsx';

I live on **Mars** but feel free to <Button title="Contact me" />.

Here is my counter component, working in MDX:

<ReactCounter client:load />
```

#### HTML 요소에 맞춤 컴포넌트 할당

MDX를 사용하면 Markdown 구문을 표준 HTML 요소 대신 사용자 정의 컴포넌트에 매핑할 수 있습니다. 이를 통해 표준 Markdown 구문으로 작성할 수 있지만 선택한 요소에 특수 컴포넌트 스타일을 적용할 수 있습니다.

사용자 정의 컴포넌트를 `.mdx` 파일로 가져온 다음 표준 HTML 요소를 사용자 정의 컴포넌트에 매핑하는 `components` 객체를 내보냅니다.

```mdx title="src/pages/about.mdx"
import Blockquote from '../components/Blockquote.astro';
export const components = {blockquote: Blockquote}

> This quote will be a custom Blockquote
```

```astro title="src/components/Blockquote.astro"
---
const props = Astro.props;
---
<blockquote {...props} class="bg-blue-50 p-4">
  <span class="text-4xl text-blue-600 mb-2">“</span>
  <slot /> <!-- 하위 콘텐츠에는 `<slot/>`을 추가하세요! -->
</blockquote>
```

사용자 정의 컴포넌트로 덮어쓸 수 있는 HTML 요소의 전체 목록을 보려면 [MDX 웹사이트](https://mdxjs.com/table-of-components/)를 방문하세요.

## Markdown 가져오기

Markdown 및 MDX 파일을 Astro 파일로 직접 가져올 수 있습니다. 이를 통해 Markdown 콘텐츠뿐만 아니라 Astro의 JSX 유사 표현식에서 사용할 수 있는 프런트매터 값과 같은 기타 속성에 액세스할 수 있습니다.

`import` 문을 사용하여 하나의 특정 페이지를 가져오거나 [`Astro.glob()`](/ko/guides/imports/#astroglob)을 사용하여 여러 페이지를 가져올 수 있습니다.

```astro title="src/pages/index.astro"
---
// 단일 파일 가져오기
import * as myPost from '../pages/post/my-post.md';

// Astro.glob을 사용하여 여러 파일 가져오기
const posts = await Astro.glob('../pages/post/*.md');
---
```

Astro 컴포넌트에서 Markdown 및 MDX 파일을 가져오면 해당 [내보낸 속성](#내보낸-속성)이 포함된 객체를 얻게 됩니다.

```md title="/src/pages/posts/great-post.md"
---
title: 'The greatest post of all time'
author: 'Ben'
---

Here is my _great_ post!
```

```astro title="src/pages/my-posts.astro"
---
import * as greatPost from '../pages/post/great-post.md';

const posts = await Astro.glob('../pages/post/*.md');
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>

<p>Post Archive:</p>
<ul>
  {posts.map(post => <li><a href={post.url}>{post.frontmatter.title}</a></li>)}
</ul>
```

MDX 파일에서는 frontmatter 및 `export` 문 모두에서 속성에 액세스할 수 있습니다.

```mdx title="/src/pages/posts/mdx-post.mdx"
---
title: 'The greatest post of all time'
author: 'Ben'
---
export const description = 'Get comfortable! This is going to be a great read.'

Here is my _great_ post!
```

```astro title="src/pages/my-posts.astro"
---
import * as greatPost from '../pages/post/mdx-post.mdx';
---

<p>{greatPost.frontmatter.title}</p>
<p>Written by: {greatPost.frontmatter.author}</p>
<p>{greatPost.description}</p>
```

TypeScript 제네릭을 사용하여 `frontmatter` 변수에 대한 타입을 선택적으로 제공할 수 있습니다.

```astro title="src/pages/index.astro" ins={2-5} ins="<Frontmatter>"
---
interface Frontmatter {
  title: string;
  description?: string;
}
const posts = await Astro.glob<Frontmatter>('../pages/post/*.md');
---

<ul>
  {posts.map(post => <li>{post.frontmatter.title}</li>)}
  <!-- post.frontmatter.title은 `string`이 됩니다! -->
</ul>
```

### 내보낸 속성

:::note[Astro 레이아웃을 사용하시나요?]
Astro의 특수한 [프런트매터 layout](#프런트매터-layout)을 사용할 때 [Astro 레이아웃 컴포넌트로 내보낸 속성](/ko/basics/layouts/#markdown-레이아웃-props)을 확인하세요.
:::

`import` 문이나 `Astro.glob()`을 사용할 때 `.astro` 컴포넌트에 다음 속성을 사용할 수 있습니다.

- **`file`** - 절대 파일 경로 (예: `/home/user/projects/.../file.md`).
- **`url`** - 페이지인 경우 페이지의 URL (예: `/en/guides/markdown-content`).
- **`frontmatter`** - 파일의 YAML 프런트매터에 지정된 모든 데이터를 포함합니다.
- **`getHeadings`** - 파일의 모든 제목 (예: `h1 -> h6` 요소)의 배열을 반환하는 비동기 함수입니다. 각 제목의 `slug`는 특정 제목에 대해 생성된 ID에 해당하며, 앵커 링크에 사용될 수 있습니다. 이 목록은 다음 타입을 따릅니다: `{ depth: number; slug: string; text: string }[]`.
- **`Content`** - 파일의 전체 렌더링된 콘텐츠를 반환하는 컴포넌트입니다.
- **(Markdown만 해당) `rawContent()`** - 원시 Markdown 문서를 문자열로 반환하는 함수입니다.
- **(Markdown만 해당) `compiledContent()`** - HTML 문자열로 컴파일된 Markdown 문서를 반환하는 함수입니다. 여기에는 프런트매터에 구성된 레이아웃이 포함되지 않습니다! Markdown 문서 자체만 HTML로 반환됩니다.
- **(MDX에만 해당)** - MDX 파일은 `export` 문을 사용하여 데이터를 내보낼 수도 있습니다.

### `Content` 컴포넌트

Markdown 또는 MDX 파일의 전체 렌더링된 콘텐츠를 반환하는 컴포넌트를 렌더링하려면 `Content`를 가져옵니다.

```astro title="src/pages/content.astro" "Content"
---
import {Content as PromoBanner} from '../components/promoBanner.md';
---

<h2>Today's promo</h2>
<PromoBanner />
```

#### 예: 동적 페이지 라우팅

페이지 경로를 생성하기 위해 Markdown/MDX 파일을 `src/pages/` 디렉터리에 두는 대신 [페이지를 동적으로 생성](/ko/guides/routing/#동적-경로)할 수 있습니다.

Markdown 콘텐츠에 액세스하려면 Astro 페이지의 `props`를 통해 `<Content/>` 컴포넌트를 전달하세요. 그런 다음 `Astro.props`에서 컴포넌트를 검색하여 페이지 템플릿에 렌더링할 수 있습니다.

```astro title="src/pages/[slug].astro" {9-11} "Content" "Astro.props.post"
---
export async function getStaticPaths() {
  const posts = await Astro.glob('../posts/**/*.md')

  return posts.map(post => ({
    params: { 
      slug: post.frontmatter.slug 
    },
    props: {
      post
    },
  }))
}

const { Content } = Astro.props.post
---
<article>
  <Content/>
</article>
```

### MDX 전용 내보내기

MDX 파일은 `export` 문을 사용하여 데이터를 내보낼 수도 있습니다.

예를 들어 MDX 페이지 또는 컴포넌트에서 `title` 필드를 내보낼 수 있습니다.

```mdx title="/src/pages/posts/post-1.mdx"
export const title = 'My first MDX post'
```

이 `title`은 `import` 및 [Astro.glob()](/ko/reference/api-reference/#astroglob) 문에서 액세스할 수 있습니다.

```astro
---
// src/pages/index.astro
const posts = await Astro.glob('./*.mdx');
---

{posts.map(post => <p>{post.title}</p>)}
```

### 가져온 MDX가 있는 사용자 정의 컴포넌트

가져온 MDX 콘텐츠를 렌더링할 때 [사용자 정의 컴포넌트](#html-요소에-맞춤-컴포넌트-할당)는 `components` prop을 통해 전달될 수 있습니다.

```astro title="src/pages/page.astro" "components={{...components, h1: Heading }}"
---
import { Content, components } from '../content.mdx';
import Heading from '../Heading.astro';
---
<!-- # 구문에 대한 사용자 정의 <h1>을 생성하고 `content.mdx`에 정의된 모든 사용자 정의 컴포넌트를 적용합니다. -->
<Content components={{...components, h1: Heading }} />
```

:::note
MDX 파일에 정의되고 내보낸 사용자 정의 컴포넌트를 가져온 다음 `components` 속성을 통해 `<Content />` 컴포넌트에 다시 전달해야 합니다.
:::

## Markdown 및 MDX 구성

Astro의 Markdown 지원은 활성 생태계를 갖춘 강력한 구문 분석 및 처리 도구인 [remark](https://remark.js.org/)를 통해 제공됩니다. Pandoc 및 markdown-it과 같은 다른 Markdown 파서는 현재 지원되지 않습니다.

Astro는 기본적으로 [GitHub-flavored Markdown](https://github.com/remarkjs/remark-gfm) 및 [SmartyPants](https://github.com/silvenon/remark-smartypants) 플러그인을 적용합니다. 이는 텍스트에서 클릭 가능한 링크 생성, [인용 및 em-dashes](https://daringfireball.net/projects/smartypants/) 서식 지정과 같은 몇 가지 장점을 제공합니다.

`astro.config.mjs` 파일에서 remark가 Markdown을 구문 분석하는 방법을 사용자 정의할 수 있습니다. [Markdown 구성 옵션](/ko/reference/configuration-reference/#markdown-옵션)의 전체 목록을 확인하세요.

### Markdown 플러그인

Astro는 Markdown 및 MDX에 대한 타사 [remark](https://github.com/remarkjs/remark) 및 [rehype](https://github.com/rehypejs/rehype) 플러그인 추가를 지원합니다. 이러한 플러그인을 사용하면 [목차 자동 생성](https://github.com/remarkjs/remark-toc), [접근 가능한 이모티콘 라벨 적용](https://github.com/florianeckerstorfer/remark-a11y-emoji), [Markdown 스타일 지정](/ko/guides/styling/#markdown-스타일링)과 같은 새로운 기능으로 Markdown을 확장할 수 있습니다.

[awesome-remark](https://github.com/remarkjs/awesome-remark) 및 [awesome-rehype](https://github.com/rehypejs/awesome-rehype)와 같은 인기 플러그인들을 찾아보시기 바랍니다! 구체적인 설치 지침은 각 플러그인의 자체 README를 참조하세요.

이 예시에서는 Markdown 및 MDX 파일 모두에 [`remark-toc`](https://github.com/remarkjs/remark-toc) 및 [`rehype-accessible-emojis`](https://www.npmjs.com/package/rehype-accessible-emojis)를 적용합니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';
import { rehypeAccessibleEmojis } from 'rehype-accessible-emojis';

export default defineConfig({
  markdown: {
    // .md 및 .mdx 파일에 적용됨
    remarkPlugins: [remarkToc],
    rehypePlugins: [rehypeAccessibleEmojis],
  },
});
```

기본적으로 `remarkToc`에서는 목차를 표시하려면 페이지에 "ToC" 또는 "Table of Contents" [heading](https://github.com/remarkjs/remark-toc?tab=readme-ov-file#options) (대소문자 구분 안 함)이 필요합니다.

#### 제목 ID 및 플러그인

Astro는 Markdown 및 MDX 파일의 모든 제목 요소 (`<h1>` ~ `<h6>`)에 `id` 속성을 삽입하고 [Markdown 내보낸 속성](#내보낸-속성)에서 이러한 ID를 검색하기 위한 `getHeadings()` 유틸리티를 제공합니다.

`id` 속성 (예: `rehype-slug`)을 삽입하는 rehype 플러그인을 추가하여 이러한 제목 ID를 맞춤설정할 수 있습니다. Astro의 기본값 대신 사용자 정의 ID가 HTML 출력과 `getHeadings()`에 의해 반환된 항목에 반영됩니다.

기본적으로 Astro는 rehype 플러그인이 실행된 후 `id` 속성을 주입합니다. 사용자 정의 rehype 플러그인 중 하나가 Astro에서 삽입한 ID에 액세스해야 하는 경우 Astro의 `rehypeHeadingIds` 플러그인을 직접 가져와 사용할 수 있습니다. 이를 사용하는 플러그인 앞에 `rehypeHeadingIds`를 추가하세요.

```js title="astro.config.mjs" ins={2, 8}
import { defineConfig } from 'astro/config';
import { rehypeHeadingIds } from '@astrojs/markdown-remark';
import { otherPluginThatReliesOnHeadingIDs } from 'some/plugin/source';

export default defineConfig({
  markdown: {
    rehypePlugins: [
      rehypeHeadingIds,
      otherPluginThatReliesOnHeadingIDs,
    ],
  },
});
```

:::note
`getHeadings()`는 Markdown 또는 MDX 파일에 직접 작성된 제목만 반환합니다. MDX 파일이 자체 제목을 포함하는 컴포넌트를 가져오는 경우, `getHeadings()`에 의해 반환되지 않습니다.
:::

#### 플러그인 맞춤설정

플러그인을 사용자 정의하려면 중첩 배열에서 플러그인 뒤에 옵션 객체를 제공하세요.

아래 예시에서는 [`remarkToc` 플러그인에 heading 옵션을 추가](https://github.com/remarkjs/remark-toc?tab=readme-ov-file#options)하여 목차 위치를 변경하고, [`rehype-autolink-headings` 플러그인에 `behavior` 옵션을 추가](https://github.com/rehypejs/rehype-autolink-headings?tab=readme-ov-file#behavior)하여 제목 텍스트 뒤에 앵커 태그를 추가했습니다.

```js title="astro.config.mjs"
import remarkToc from 'remark-toc';
import rehypeSlug from 'rehype-slug';
import rehypeAutolinkHeadings from 'rehype-autolink-headings';

export default {
  markdown: {
    remarkPlugins: [ [remarkToc, { heading: "contents"} ] ],
    rehypePlugins: [rehypeSlug, [rehypeAutolinkHeadings, { behavior: 'append' }]],
  },
}
```

### 프로그래밍 방식으로 프런트매터 수정하기

:::note
[콘텐츠 컬렉션](/ko/guides/content-collections/)을 사용하는 경우, ["프런트매터를 Remark로 수정하기"](/ko/guides/content-collections/#프런트매터를-remark로-수정하기)을 참조하세요.
:::

[remark 또는 rehype 플러그인](#markdown-플러그인)을 사용하여 모든 Markdown 및 MDX 파일에 프런트매터 속성을 추가할 수 있습니다.

1. 플러그인의 `file` 인수에서 `data.astro.frontmatter` 속성에 `customProperty`를 추가합니다.

    ```js title="example-remark-plugin.mjs"
    export function exampleRemarkPlugin() {
      // 모든 remark 및 rehype 플러그인은 별도의 함수를 반환합니다.
      return function (tree, file) {
        file.data.astro.frontmatter.customProperty = 'Generated property';
      }
    }
    ```

    :::tip
    <Since v="2.0.0" />

    `data.astro.frontmatter`에는 특정 Markdown 또는 MDX 문서의 모든 속성이 포함되어 있습니다. 이를 통해 기존 프런트매터 속성을 수정하거나 기존 프런트매터에서 새 속성을 계산할 수 있습니다.
    :::

2. 이 플러그인을 `markdown` 또는 `mdx` 통합 구성에 적용하세요.

    ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

    export default defineConfig({
      markdown: {
        remarkPlugins: [exampleRemarkPlugin]
      },
    });
    ```

    또는

    ```js title="astro.config.mjs" "import { exampleRemarkPlugin } from './example-remark-plugin.mjs';" "remarkPlugins: [exampleRemarkPlugin],"
    import { defineConfig } from 'astro/config';
    import { exampleRemarkPlugin } from './example-remark-plugin.mjs';

    export default defineConfig({
      integrations: [
        mdx({
          remarkPlugins: [exampleRemarkPlugin],
        }),
      ],
    });
    ```

이제 모든 Markdown 또는 MDX 파일의 프런트매터에 `customProperty`가 있으므로 [Markdown을 가져올 때](#markdown-가져오기) [레이아웃의 `Astro.props.frontmatter` 속성](#프런트매터-layout)에서 사용할 수 있습니다.

<RecipeLinks slugs={["ko/recipes/reading-time"]} />

### MDX에서 Markdown 구성 확장

Astro의 MDX 통합은 기본적으로 [프로젝트의 기존 Markdown 구성](/ko/reference/configuration-reference/#markdown-옵션)을 확장합니다. 개별 옵션을 재정의하려면 MDX 구성에서 해당 옵션을 지정하면 됩니다.

다음 예시에서는 GitHub 기반 Markdown을 비활성화하고 MDX 파일에 대해 다른 remark 플러그인 세트를 적용합니다.

```ts title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    syntaxHighlight: 'prism',
    remarkPlugins: [remarkPlugin1],
    gfm: true,
  },
  integrations: [
    mdx({
      // Markdown에서 상속된 `syntaxHighlight`

      // Markdown `remarkPlugins`가 무시되었습니다.
      // `remarkPlugin2`만 적용됩니다.
      remarkPlugins: [remarkPlugin2],
      // `gfm`이 `false`로 재정의됨
      gfm: false,
    })
  ]
});
```

MDX에서 Markdown 구성을 확장하지 않으려면 [`extendMarkdownConfig` 옵션](/ko/guides/integrations-guide/mdx/#extendmarkdownconfig) (기본적으로 활성화됨)을 `false`로 설정하세요.

```ts title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import mdx from '@astrojs/mdx';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkPlugin],
  },
  integrations: [
    mdx({
      // Markdown 구성은 이제 무시됩니다.
      extendMarkdownConfig: false,
      // 'remarkPlugins'가 적용되지 않았습니다.
    })
  ]
});
```

### 구문 강조

Astro에는 [Shiki](https://shiki.style/) 및 [Prism](https://prismjs.com/)에 대한 지원이 내장되어 있습니다. 이는 다음에 대한 구문 강조를 제공합니다.

- Markdown 또는 MDX 파일에 사용되는 모든 코드 펜스(\`\`\`).
- [내장 `<Code />` 컴포넌트](/ko/reference/api-reference/#code-)의 콘텐츠 (Shiki 제공).
- [`<Prism />` 컴포넌트](/ko/reference/api-reference/#prism-)의 콘텐츠 (Prism 제공).

Shiki는 기본적으로 활성화되어 있으며 `github-dark` 테마로 사전 구성되어 있습니다. 컴파일된 출력은 외부 CSS 클래스, 스타일시트 또는 클라이언트 측 JS가 없는 인라인 `스타일`로 제한됩니다.

#### Shiki 구성

Shiki는 기본 구문 강조 도구입니다. 다음과 같이 `shikiConfig` 객체를 통해 모든 옵션을 구성할 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    shikiConfig: {
      // Shiki에 내장된 테마 중에서 선택하거나 직접 추가하세요.
      // https://shiki.style/themes
      theme: 'dracula',
      // 또는 여러 테마를 제공하세요.
      // https://shiki.style/guide/dual-themes#light-dark-dual-themes
      themes: {
        light: 'github-light',
        dark: 'github-dark',
      },
      // 사용자 정의 언어 추가
      // 참고: Shiki에는 .astro를 포함하여 수많은 언어가 내장되어 있습니다!
      // https://shiki.style/languages
      langs: [],
      // 가로 스크롤을 방지하려면 word wrap을 활성화하세요.
      wrap: true,
      // 맞춤 transformers 추가: https://shiki.style/guide/transformers
      // 일반 transformers 찾기: https://shiki.style/packages/transformers
      transformers: [],
    },
  },
});
```

#### 나만의 테마 추가하기

Shiki의 사전 정의된 테마 중 하나를 사용하는 대신 로컬 파일에서 사용자 정의 테마를 가져올 수 있습니다.

```js title="astro.config.mjs"
import { defineConfig } from 'astro/config';
import customTheme from './my-shiki-theme.json';

export default defineConfig({
  markdown: {
    shikiConfig: { theme: customTheme },
  },
});
```

또한 테마, 밝은 모드와 어두운 모드 전환 또는 CSS 변수를 통한 스타일 지정에 대해 자세히 알아보려면 [Shiki의 자체 테마 문서](https://shiki.style/themes)를 읽어보는 것이 좋습니다.

#### 기본 구문 강조 모드 변경

기본적으로 `prism'`으로 전환하거나 구문 강조를 완전히 비활성화하려면 `markdown.syntaxHighlight` 구성 객체를 사용할 수 있습니다.

```js title="astro.config.mjs" ins={6}
import { defineConfig } from 'astro/config';

export default defineConfig({
  markdown: {
    // 'shiki' (기본값), 'prism' 또는 강조를 비활성화 하기 위한 false일 수 있습니다.
    syntaxHighlight: 'prism',
  },
});
```

#### Prism 구성

Prism을 사용하기로 선택한 경우 Astro는 대신 Prism의 CSS 클래스를 적용합니다. 구문 강조를 표시하려면 **자신만의 CSS 스타일시트를 가져와야 합니다**.

1. 사용 가능한 [Prism 테마](https://github.com/PrismJS/prism-themes)에서 미리 만들어진 스타일시트를 선택합니다.
2. 이 스타일시트를 [프로젝트의 `public/` 디렉터리](/ko/basics/project-structure/#public)에 추가하세요.
3. `<link>` 태그를 통해 [레이아웃 컴포넌트](/ko/basics/layouts/)에 있는 페이지의 `<head>`에 이를 로드합니다. ([Prism 기본 사용법](https://prismjs.com/#basic-usage)을 참고하세요.)

옵션 및 사용법을 알아보려면 [Prism에서 지원하는 언어 목록](https://prismjs.com/#supported-languages)을 방문하세요.

## 원격 마크다운 가져오기

Astro는 주로 프로젝트 디렉터리에 저장할 수 있는 로컬 Markdown 파일용으로 설계되었습니다. 그러나 원격 소스에서 Markdown을 가져와야 하는 특정 경우가 있을 수 있습니다. 예를 들어, 웹 사이트를 구축할 때 (또는 [SSR](/ko/guides/server-side-rendering/)을 사용하는 경우, 사용자가 웹 사이트에 요청할 때) 원격 API에서 Markdown을 가져오고 렌더링해야 할 수 있습니다.

**Astro에는 원격 Markdown에 대한 기본 지원이 포함되어 있지 않습니다!** 원격 Markdown을 가져와 HTML로 렌더링하려면 npm에서 자체 Markdown 파서를 설치하고 구성해야 합니다. 이는 Astro의 기본 제공 Markdown 및 사용자가 구성한 MDX 설정에서 상속되지 **않습니다**. 프로젝트에 이를 구현하기 전에 이러한 제한 사항을 이해해야 합니다.

```astro title="src/pages/remote-example.astro"
---
// 예: 원격 API에서 마크다운 가져오기
// 런타임에 HTML로 렌더링합니다.
// "marked" 사용 (https://github.com/markedjs/marked)
import { marked } from 'marked';
const response = await fetch('https://raw.githubusercontent.com/wiki/adam-p/markdown-here/Markdown-Cheatsheet.md');
const markdown = await response.text();
const content = marked.parse(markdown);
---
<article set:html={content} />
```
